/*!
\copyright  Copyright (c) 2025 Qualcomm Technologies International, Ltd.
            All Rights Reserved.
            Qualcomm Technologies International, Ltd. Confidential and Proprietary.
\file
\brief      Helper definitions for audio connections
*/

#ifndef KYMERA_CONNECT_UTILS_H_
#define KYMERA_CONNECT_UTILS_H_

#include <source.h>
#include <sink.h>
#include <chain.h>

/**
 *  \brief Connect if both Source and Sink are valid.
 *  \param source The Source data will be taken from.
 *  \param sink The Sink data will be written to.
 *  \note In the case of connection failuar, it will panics the application.
 * */
void Kymera_ConnectIfValid(Source source, Sink sink);

/**
 *  \brief Break any existing automatic connection involving the source *or* sink.
 *   Source or sink may be NULL.
 *  \param source The source which needs to be disconnected.
 *  \param sink The sink which needs to be disconnected.
 * */
void Kymera_DisconnectIfValid(Source source, Sink sink);

/**
 * \brief
 * \param source_list - Array of chain endpoint sources to be connected
 * \param source_count - Number of sources in source_list
 * \param output_sample_rate - The output sample rate to be set
 * */
void Kymera_ConnectOutputSourceList(Source *source_list, uint8 source_count, uint32 output_sample_rate);

/**
 * \brief Map mics to sinks based on the chain input roles and mic roles
 *
 * \param[out] mic_ids Array of mics that map to chain inputs
 * \param[out] mic_sinks Array of sinks from the chain that map to the mics in the mic_ids array
 * \param[in] num_mics Maximum number of mics that can be mapped. I.e. size of the mic_ids/mic_sinks arrays
 * \param[in] chain Chain handle of the chain which inputs the function should map to mics
 *
 * \return The number of mic_ids/mic_sinks that have been matched and populated in the arrays.
 * 
 * Examples based on the following microphone configuration:
 * 
 * static const int mic0_roles[] = {
 *     MIR_VOICE,
 *     MIR_ANC_FEED_FORWARD_LEFT,
 * 
 *     EPR_CVC_SEND_IN1,
 *     EPR_MIC_MIC1_IN,
 * };
 * 
 * static const int mic1_roles[] = {
 *     MIR_EXTERNAL,
 *     MIR_ANC_FEED_FORWARD_RIGHT,
 * 
 *     EPR_CVC_SEND_IN2,
 * };
 * 
 * static const microphones_mic_config_t platform_microphone_configs[] = {
 *     {
 *         .params = {
 *             .bias_config = BIAS_CONFIG_MIC_BIAS_0,
 *             .pio = 19,
 *             .type = mic_type_analog,
 *             .instance = AUDIO_INSTANCE_0,
 *             .channel = AUDIO_CHANNEL_A,
 *         },
 *         .roles = mic0_roles,
 *         .num_roles = ARRAY_DIM(mic0_roles),
 *     },
 *     {
 *         .params = {
 *             .bias_config = BIAS_CONFIG_MIC_BIAS_0,
 *             .pio = 22,
 *             .type = mic_type_analog,
 *             .instance = AUDIO_INSTANCE_0,
 *             .channel = AUDIO_CHANNEL_B,
 *         },
 *         .roles = mic1_roles,
 *         .num_roles = ARRAY_DIM(mic1_roles),
 *     },
 * };
 * 
 * 1 - A chain has a single input that should be connected to a microphone, EPR_MIC_MIC1_IN
 * 
 * uint16 mic_ids[1];
 * Sink mic_sinks[1];
 * uint16 num_mics = 1;
 * 
 * kymera_chain_handle_t chain = kymeraGetExampleChain(); // Placeholder function, not implemented.
 * 
 * // This will map mic0 to the chain input with the EPR_MIC_MIC1_IN Endpoint Role.
 * uint16 mapped_mics = Kymera_MapMicsToChainInputs(uint16 *mic_ids, Sink *mic_sinks, uint16 num_mics, kymera_chain_handle_t chain);
 * 
 * 2 - A chain has two inputs that should be connected to two microphones, EPR_CVC_SEND_IN1 and EPR_CVC_SEND_IN2
 * 
 * uint16 mic_ids[2];
 * Sink mic_sinks[2];
 * uint16 num_mics = 2;
 * 
 * kymera_chain_handle_t chain = kymeraGetExampleChain(); // Placeholder function, not implemented.
 * 
 * // This will map mic0 to the chain input with the EPR_MIC_MIC1_IN Endpoint Role and mic1 to the chain input with the EPR_MIC_MIC2_IN Endpoint Role.
 * uint16 mapped_mics = Kymera_MapMicsToChainInputs(uint16 *mic_ids, Sink *mic_sinks, uint16 num_mics, kymera_chain_handle_t chain);
 * 
 */
uint16 Kymera_MapMicsToChainInputs(uint16 *mic_ids, Sink *mic_sinks, uint16 num_mics, kymera_chain_handle_t chain);
#endif /* KYMERA_CONNECT_UTILS_H_ */
